Cream of the Crop 22/Cream of the Crop 22.iso/utility/uuexe656.zip/UUSER.TXT

Text File | 1996-09-18 | 22KB | 536 lines

This file contains user documentation for the UUENCODE/DECODE pair.


SUMMARY:

This package encodes and decodes "UUencoded files".  UUencoding is a
popular technique for reliably sending binary files over communications
systems.  Common binary files are "zip files" produced by pkzip, gif and
jpg picture files, and doc files produced by word processors.  To send a
binary file, UUencode the file and send it out with your favorite e-mail
or communications program.  To receive the file, download the UUencoded
version to your PC and UUdecode it.

There are many public domain UUencoders and decoders.  This pair was
originally written in 1987 and has been kept up to date since; it is
designed to handle just about anything you can throw at it with ease.

For more details on how to use the UUENCODE and UUDECODE programs, read
this document.  For a technical description of the UUencode process, see
UUTECH.TXT.


SIMPLE, COMMON USE:

To decode a file, download it to your PC.  Give the filename an
extension of ".UUE".  (ie: FOO.UUE); this aids you in identifying it as
a uuencoded file.  If the file was sent out in multiple parts, put the
part number on the end of the file name (ie: FOO1.UUE, FOO2.UUE, etc.).

Then enter: UUDECODE FOO

The name of the file to decode into is saved in the encoded file; so you
do not have to supply it.

To encode a file, enter: UUENCODE filename

There are all kinds of options, which are described below; but you
should ignore them if the above works for you.


DISCLAIMER:

This program was written by me, Richard Marks, and it is copyrighted.
Please see  the copyright notice in UUTECH.TXT.

The program is freeware for personnal, private use.  If used in any
other way, please contact me - there is a modest charge.

The feature of MIME Base64 decoding is available as a $20 option.
My address is at the end of this file.

The feature of Encryption with encoding and decoding is available as
a $34.95 option.   Please see the discussion of encryption below.

************************************************************************

UUENCODE:

UUencode a file to send it out over a communications system (e-mail).
Most e-mail systems limit the size of a single message.  A typical limit
is 64 thousand bytes.  UUencode splits the encoded file into parts which
can be sent out one at a time.  Thus a very large file is sent out as
a number of smaller files that are within size limits.

UUencode can automatically put checksum characters in the encoded file
so the decode program can do validation.  (Modern communications systems
are so reliable that one rarely sees a checksum error when decoding, but
I still think it is a good idea to leave checksum-ing turned on just to
be sure there are no problems.  This adds at most a few seconds to
encoding and decoding times.)

The command:

    UUENCODE  [options]  input-file  [output-file]

    Popular options:
       -c     - Do not create any checksums. (Checksums recommended!)

       -s     - Do NOT split the encoded file into sections.

       -s nnn - Split the encoded file into sections of nnn lines,
                or nnK byte sections.
                Default is split into 950 line sections.

       -h nnn - Leave room in first section for nnn header (extra
                comment) lines.

       -x     - Use XX encoding (see below).

       -6     - Use Base64 MIME compliant encoding (see below).

    Less Popular options:
       -o     - write to standard output, not to a file.
                No splitting is done in this case.

       -L     - Insert checksums on every line.  This is an old option
                for use with unreliable communication systems.

       -t     - Write the mapping table that was used into the encoded
                file (see below).

       -u     - Unix format file (Unix end of line character).


UUENCODE INPUT FILE NAME:

The input file name must be supplied.  It is the name of the file to be
encoded.  The file name and extension, but not the drive or path, is
saved in the encoded file.  This name is used by UUdecode to recreate a
file with the same name.


UUENCODE OUTPUT FILE NAME (of the encoded file):

This is an optional parameter.  Normally it is not needed.

Naming can get a little complicated if you are creating split files.  So
let's take things in little steps.  (The problem is that in automated
systems, there is a need for a variety of ways to specify file names.)

First, the normal case is with no output file name supplied:

        Output file name is input file name, with a ".UUE" extension.
        Output is to the current directory; the drive & directory
        of the input file is ignored.

        UUENCODE FOO.BAR  creates FOO.UUE

If you supply an output file name, it is used.  If the output file name
you supply does not have an extension, ".UUE" is used.

        UUENCODE FOO.BAR  ABC.DEF  creates ABC.DEF
        UUENCODE FOO.BAR  ABC      creates ABC.UUE
        UUENCODE FOO.BAR  ABC.     creates ABC.

Note the subtly of the last example.  The "." after "ABC" is an
extension of all spaces; so there is no extension on the output file.
This differs from the second example where, since there is no ".", the
default extension of ".UUE" is supplied.

Normally output is put in to the directory you are in when you enter
the UUencode command (the current directory).  This happens even if the
input file is in some other directory.  But if a drive and/or directory
is specified for the output file, it is used.

If you want to use the input file's drive & directory, use a directory
of *\ for the output file.  The input file's drive & directory is used.

          UUENCODE ZZZ\FOO.BAR         creates FOO.UUE
          UUENCODE ZZZ\FOO.BAR  ABC    creates ABC.UUE
          UUENCODE ZZZ\FOO.BAR  *\ABC  creates ZZZ\ABC.UUE
          UUENCODE ZZZ\FOO.BAR  *\     creates ZZZ\FOO.UUE

The *\ options are very useful in automated systems.


SPLIT FILES and OUTPUT FILE NAMES:

UUencode checks the size of your file, if it is too small to split, the
naming convention above is used.  If the file is larger, the part number
is put into the part name as described below.

Normally UUencode splits encoded files by putting a number after the
file name.
         UUENCODE FOO.BAR           creates FOO1.UUE, FOO2.UUE, etc.
         UUENCODE FOO.BAR    *.ZZZ  creates FOO1.ZZZ, FOO2.ZZZ, etc.
         UUENCODE FOO.BAR  ABC.ZZZ  creates ABC1.ZZZ, ABC2.ZZZ, etc.

Another popular way to name split files is with the extension of .001,
.002, etc.  If you specify an output file extension of .001, then this
naming convention is used.

        UUENCODE FOO.BAR  ABC.001   creates ABC.001, ABC.002, etc.
        UUENCODE FOO.BAR    *.001   creates FOO.001, FOO.002, etc.

(I personally prefer to use the ".UUE" extension so I can determine that
this is a UUencoded file from the file name; but some prefer the .001
naming convention.  The .UUE extension is strongly recommended for
Windows95 users.)


XXENCODING (the -x and -t options):

UUencode maps a binary file into a certain character set.  This
character set goes through most communications systems with no problems.
However some communications systems change some of the special
characters used by UUencode.  For example the "{" character is changed
into a "<" on some systems.

If you are having this sort of problem mailing to a friend, read on.

One could argue that it was a bad decision for UUencode to use
characters that may be changed.  But many years ago, it was hard to find
enough characters that could go over all communications systems
unchanged.  Maybe 15 years ago, the characters that UUencode uses were
a good choice; but today there are other options.

The XXencode option, is a better choice.  It uses characters that
usually get through with no problems.  (It uses some lower case
characters; lower case was not common on all computers 15 years ago.)
Unfortunately, XXdecoders are not as commonly available as UUencoders.
If the person you are mailing to has an XXdecoder, try the "-x" option
on UUencode.  My UUdecoder automatically detects and handles XX encoded
files.  Note that the default file extension is .XXE for XX encoded
files.

Another option is to send out the mapping table that UUencode uses.
Then whatever gets changed, gets changed in the mapping table and in the
data, so the decode will decode correctly.  If the person you are
mailing to has a UUdecoder that accepts mapping tables, try the -t
option on UUencode.  You can use -x and -t together, but there is no
reason to do this.  My UUdecoder handles mapping tables.  Note that if a
file is changed, UUdecode will report an input file checksum error.
This is OK as long as it does not report an output file checksum error
(what comes out is the important thing).


Base64 (MIME Compliant) ENCODING:

There is a generalized Mail system (MIME) that can use a variety of
encoding techniques.  These include UU, XX, and a new slightly more
efficient encoding method called Base64.  The -6 option enables this
form of encoding.  It also disables all checksums and the table option.

Do not use this mechanism unless you are certain that the recepiant can
handle it.  MIME decoders are not yet as popular as UUdecoders.

Base64 encoding has one major design problem that is so severe that I
strongly recommend not using it unless required !

The specific problem is that, based on the MIME standard RFC 1521,
there is no way to check for missing or corrupted characters.  Now on
modern systems, the underlying file transfer mechanism (TCP, Zmodem)
is supposed to guarantee reliable delivery.  But as you all know,
there are errors.  Base64 has no way to detect errors; UU does.

My Base64 decoder prints a message when lines of different lengths
are encountered.  If you know the encoded file will have such lines,
you can suppress the tests with the -L decoding option.

MIME has another design problem with multi-part encoded files.  There is
no "end" marker; the decoder knows how many parts there are by a count
in the header lines.  But some MIME encoders (notably the one used when
AOL automatically splits files into sections) do not put in these count
lines.  Thus the decoder does not know this is a multi-part encoding.
The solution is to use the "-p" option. followed by the number of parts.

    UUDECODE -6 -p 3  foo1.b64

My uudecoder can accept Base64, but to make a little money, it is a
$20 option.  Please see my address below.

************************************************************************

UUDECODE:

UUdecoding is the inverse of UUencoding.  The input is a UUencoded file
or a several split UUencoded files.  The output is what the original
UUencode started with.

This UUdecode automatically checks for just about everything.  It
automatically handles split files, checksums, files packaged with the
Unix 'sed' program, and UU or XX encoding.  But more importantly, over
the years I have encountered many different minor problems and
eccentricities of various communications systems.  (Even CompuServe and
GEnie do, on occasion, insert some weird stuff in the middle of your
files.)  This UUdecode handles all this sort of stuff.

In most cases you can just download a whole set of files as:
     FOO1.UUE, FOO2.UUE, etc.
then just enter:
     UUDECODE FOO
with no editing or anything else and "poof" the thing will decode.
(If you have registered UUdecode under Windows 3.1 or 95, you can
double click on the .UUE file to decode it.)

The majority of decode problems are related to the PC learning curve
(file naming and directories) or to downloading problems.  However
sometimes you will have a problem situation which occurs when decoding
files from one particular site.  This may require special procedures for
handling files from just that site.

The typical site related problem is caused by a non-standard UUencoder.
I have seen a lot of encoded files, but if you think there is a problem,
please contact me.  (Contact info is at the end of this writeup.)

The command:

    UUDECODE  [options]  input-file  [output-file]

    popular options:
        none - normally you do not use any options with UUdecode


    less popular options:
        -c/C - do not do any checksum testing.  If upper case "C",
               checksum testing is done on the output file but not
               on any input files (see below)

        -L   - do not do line level checks (see below)

        -s   - do not handle split files

        -i   - take input from stdin (implies -s)

        -u/x - use UU or XX decoding, do not do automatic analysis

        -6   - use Base64 decoding ($20 feature), no automatic analysis

        -p n - file is encoded in N parts, used for some Mime Base64
               encoders that do not prperly include the number of parts.


    options for use in automated systems (see UUTECH.TXT):
        -e/E - call .bat file when decoding complete.

        -q   - quiet operation (no beeps)

        -y   - force "yes" response to all prompts.

        -n   - force "no" response to all prompts.

        -z   - use specific "cut" line.

Options can be entered in upper or lower case unless, like for c/C,
there is a specific meaning for each case.


CHECKSUM TESTING:

Normally you will want to run UUdecode with all checksum options on.

For the novice - what is a checksum?  When all the alphabet soup
UUencoded characters are processed, they are sent through a
mathematical formula that produces a number.  This number is included
at the end of the encoded file.  When decoding, if the calculated
number matches the number included in the file, there is a pretty
good chance the file decoded correctly.

Why do I say "a pretty good chance"?  The checksum formula is designed
to catch changes in a few characters and simple transpositions and
omissions.  But if the file is really corrupted, there is a one in two
million chance that the corrupted file will produce a checksum number
that matches.

Occasionally you will encounter a file with junk appended to lines and
UUdecode will display messages stating something is wrong with a
specific line.  You may then accept or reject the line.  If you accept
all the supposedly invalid lines and if the resultant file proves
correct, run UUdecode with the -L option to suppress these errors.  Also
let me know of the details as this is some unknown UUencoder that I want
to handle.  See the "contact" section at the end of this document.

Some UUencoders insert checksum information in the encoded file.
In many cases if the input file is bad, the output file is also bad.
But frequently the problem with the input file does not affect the
output file.  If you get messages about checksum errors on input files
and the output file is correct, run UUdecode with the -C (upper case)
option to turn off input file checksum tests.

If you do get input file checksum errors, they should be understood.
Even if the file decodes with no output file checksum errors; you
should be certain the problem will not cause output file problems in
the future.

It is possible, but unlikely, that the output file may have checksum
errors and still be acceptable.  You can turn off all checksum testing
with the -c (lower case) option.  Note: -C or -c imply the -L option.


FILE NAMING:

UUDECODE INPUT FILE NAME:

The problem with input file names is that you may be working with split
files.  Perhaps file FOO.EXE is encoded in two parts and you have
downloaded them as FOO1.UUE and FOO2.UUE.  If you supply UUdecode an
input file name of FOO1.UUE, then it will find this file, decode it and
go to FOO2.UUE automatically.

However, most users, myself included, have the mind set that they are
working with file FOO and "forget all this other stuff please".  To
handle this situation, UUdecode scans for several variations of the
input file name you supply.

If you supply a file name with an extension, FOO.XYZ, that file name is
used.  If not found, then UUdecode puts the number '1' after the file
name (FOO1.XYZ) and UUdecode tries again.

The more common case is where just the file name, with no extension is
supplied:
        UUDECODE FOO

UUdecode tries the files in the following order:

        FOO.UUE
        FOO.XXE         xx encoded file
        FOO1.UUE
        FOO1.XXE
        FOO.001
        FOO.01
        FOO.1
        FOO.
        FOO1.

This may seem complicated, but it runs quickly.

A drive and directory may also be supplied:

        UUDECODE C:\MYDIR\FOO

All the above rules apply.  But the given drive & directory is scanned.


UUDECODE OUTPUT FILE NAME:

Normally the name of the output file is obtained from the encoded file;
it was put there when the file was encoded.  The decoded file is
recreated with this file name.  The file is put into the current
directory (the directory from which the UUdecode command is executed).

There are several ways to alter this.

If you want to specify a specific output file name, optionally with
drive and directory, specify it as the second file on the command line:

        UUDECODE FOO  c:\ABC\MYOUT.XXX

If you want to use the name from within the encoded file, but with a
specific drive and directory, use the drive:directory with a '*' as the
file name:

        UUDECODE FOO  c:ABC\*

If you want to use the drive and directory of the input file, use a '*'
as the directory name:

        UUDECODE c:ABC\FOO   *\NAME.NEW    drive & dir from encoded file
        UUDECODE c:ABC\FOO   *\            file name from encoded file

************************************************************************

WINDOWS 95

While this is a DOS program, I use it under Windows95 all the time.
Actually Windows95 "Drop, drag, and double click" makes this program
almost as easy to use as a Windows program.  After things are properly
set up all you will have to do is double click on a ".UUE" file and it
will decode.

The trick is file types and registration.  Included with this package
is a "reg" file for Win95.  After you load this package on your
machine, use the Explorer to go to the folder you put it in and find
the UUDECODE.REG file.

Right mouse click once on the .REG file and click on "Edit".  Change the
lines containing c:\???\UUDECODE.EXE to state the folder where UUDECODE
resides.  (The machine is not magic, it's somehow gotta know where the
program is.  I suggest putting UUENCODE.EXE and UUDECODE.EXE in your
C:\DOS directory.)  Save the editted .REG file.  Then double click on
it; this will run the Registry program.

The net result is that the .UUE, .XXE, and .B64 file types will be
registered with Win95. Then when you double click on a file which is
one of these types, UUDECODE, with the correct options to decode that
file will be started.

************************************************************************

ENCRYPTION

A new option has been added to this package to encrypt and encode/decode
files.  Encryption/Decryption is done by just supplying a Security Key
when you run UUencode or UUdecode - nothing else is required.

     UUENCODE  -K mykey  File
     UUDECODE  -K mykey

The same key is used to create and to read the file.  Getting the key to
the receipient, in a secure manner, is your challange.  Keys may be up
to 30 characters long; spaces and other special characters may be in the
key for readability, but are ignored.  The key is case insensitive.  A
very long key means a very high degree of security.  For example:

        UUENCODE -K 'Have a very nice sunny day' File

A very secure, high dispersion algorithm with a 160 bit key is used.
For best security, send the smallest possible file.  The more data your
opponent has, the easier it is to break the code.

I call the Encode/Decode package with encryption UUSECURE.  UUSECURE
costs $34.95.  For an extra $5, I include the Base64 decoding feature,
which seperately is a $20 option.

Cavaets:

There is no way I can figure out the key; do not contact me if you
forget it.

Please remember that all encryption algorithms can be broken; if you use
this program, you must agree that I cannot be held responsible if
somebody breaks the code.  If you have problems with this, please do not
use the program.

This program falls under export control laws.  It uses too secure an
encryption scheme for the government to permit it to be exported.  Do
not export it unless you want the Feds at your doorstep.

I will soon offer a legal international version that will be programmed
in and will be shipped from South Africa.  For international ordering
information; please contact me.

For developers I offer the kernal of the encryption subroutines as an
OLE2 Automation Control.  Very easy to use from VB and Access.

************************************************************************
CONTACTING THE AUTHOR:

You can mail me:
        Richard Marks
        931 Sulgrave Lane
        Bryn Mawr, PA  19010
        USA

If you encounter a problem I will need to see exactly what you are
working with.  Please send me a diskette with whatever you think is
important.  You can put a 3 1/2" diskette in an envelope with no special
precautions and a single stamp.

You may telephone me at [phone].  I am usually home after 7PM and
stay up till 11PM - US Eastern Time; it is OK to call then.

The latest registered version is available from www.alberts.com, an internet
software store.